<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>12. Pmemcheck: persistent memory analyzer</title>
<link rel="stylesheet" type="text/css" href="vg_basic.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="lk-manual.html" title="11. Lackey: an example tool">
<link rel="next" href="nl-manual.html" title="13. Nulgrind: the minimal Valgrind tool">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
<td width="22px" align="center" valign="middle"><a accesskey="p" href="lk-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
<td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td>
<th align="center" valign="middle">Valgrind User Manual</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="nl-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="pmc-manual"></a>12. Pmemcheck: persistent memory analyzer</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="sect1"><a href="pmc-manual.html#pmc-manual.overview">12.1. Overview</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="pmc-manual.html#pmc-manual.functionality">12.1.1. Functionality</a></span></dt>
<dt><span class="sect2"><a href="pmc-manual.html#pmc-manual.basic_usage">12.1.2. Basic Usage</a></span></dt>
<dt><span class="sect2"><a href="pmc-manual.html#pmc-manual.error_types">12.1.3. Pmemcheck error types</a></span></dt>
<dt><span class="sect2"><a href="pmc-manual.html#pmc-manual.transactions">12.1.4. Pmemcheck transaction support</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="pmc-manual.html#pmc-manual.options">12.2. Pmemcheck Command-line Options</a></span></dt>
<dt><span class="sect1"><a href="pmc-manual.html#pmc-manual.client_requests">12.3. Pmemcheck Client Requests</a></span></dt>
<dt><span class="sect1"><a href="pmc-manual.html#pmc-manual.monitor_commands">12.4. Pmemcheck Monitor Commands</a></span></dt>
</dl>
</div>
<p>
    To use this tool, you must specify<code class="option">--tool=pmemcheck</code>
    on the Valgrind command line.
  </p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="pmc-manual.overview"></a>12.1. Overview</h2></div></div></div>
<p>
      Pmemcheck is a persistent memory profiler, which helps analyze the
      way user applications utilize persistent memory. It helps recognize
      whether the correct store scheme is used and that data is made
      persistent. With additional options it can also be used to log all
      writes to a specific memory region and to identify whether persistent
      memory is used as volatile memory. Pmemcheck is loosely based on
	  Memcheck.
    </p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pmc-manual.functionality"></a>12.1.1. Functionality</h3></div></div></div>
<p>
        Pmemcheck instruments client code and tracks all stores made to a user
        provided range of memory addresses. Writing applications which make use
        of persistent memory prove to be a challenge, because memory is not
        reclaimed automatically on reboot. Because of the specific nature of
        persistent memory, the store scheme	has to follow a special pattern.
        To make the data persistent, preferably in a failsafe manner, you have
        to do a	<span class="emphasis"><em>STORE-&gt;FLUSH-&gt;SFENCE</em></span>
        sequence. Pmemcheck checks if this particular sequence of operations
        is made to any of the registered persistent memory regions. On program
        exit pmemcheck informs of all improperly made stores by providing the
        address, size and state of the store. Additionally if debug information
        is available, the stack trace of the offending write will be shown.
        The available states are:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
            <code class="option">DIRTY</code> - a write has been made
          </p></li>
<li class="listitem"><p>
            <code class="option">FLUSHED</code> - the write has been flushed
          </p></li>
</ul></div>
<p>
        For more information on persistent memory programming, please visit
        <a class="ulink" href="http://pmem.io" target="_top">pmem.io</a>.
      </p>
<p>
        The tool, when run with the <a class="xref" href="pmc-manual.html#opt.mult-stores">--mult-stores</a>
        option, can also track multiple stores to the same location
        before the data is made persistent - goes through all the states in the
        right order. This might indicate that there is something wrong with your
        application, because you are using persistent memory as volatile memory.
        If this is the desired use, you can remove the volatile region from
        analysis using the <a class="xref" href="pmc-manual.html#crm.rem_pmem">VALGRIND_PMC_REMOVE_PMEM_MAPPING</a> macro.
      </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pmc-manual.basic_usage"></a>12.1.2. Basic Usage</h3></div></div></div>
<p>
        As with most other Valgrind tools, compiling your program with debugging
        info (the <code class="option">-g</code> option) provides the most valuable output.
      </p>
<p>
        To run your program under pmemcheck execute:
        </p>
<pre class="screen">valgrind --tool=pmemcheck [pmemcheck options] your_program [program options]</pre>
<p>
      </p>
<p>
          For the tool to be able to correctly inspect your program, you should
          inform it about the persistent memory specific operations your
          application performs. At the moment, pmemcheck does not automatically
          recognize persistent memory regions, appropriate flushes or fences.
          Your code has to use special macros specified in
          <a class="xref" href="pmc-manual.html#pmc-manual.client_requests" title="12.3. Pmemcheck Client Requests">Pmemcheck Client Requests</a>.
      </p>
<p>
        Pmemcheck also has a logging functionality, which when enabled, logs
        all persistent memory relevant macros as well as all stores made
        to the registered persistent memory regions. This is especially useful
        for any kind of postprocessing. To turn this option on, run pmemcheck
        with <a class="xref" href="pmc-manual.html#opt.log-stores">--log-stores</a>.
      </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pmc-manual.error_types"></a>12.1.3. Pmemcheck error types</h3></div></div></div>
<p>
        Pmemcheck is able to catch a couple of possible errors related to
        programming using persistent memory. The most probable is that some
        stores are never made persistent, which together with power failures,
        may leave the persistent memory in an inconsistent state. If debugging
        symbols are available, the output of such an error looks like this:
        </p>
<pre class="programlisting">
Number of stores not made persistent: 3
Stores not made persistent properly:
[0]    at 0x400A73: main (state_machine2.c:29)
	Address: 0x4fec000	size: 1	state: FENCED
[1]    at 0x400B56: main (state_machine2.c:32)
	Address: 0x4fec008	size: 2	state: FLUSHED
[2]    at 0x400BB8: main (state_machine2.c:34)
	Address: 0x4fec010	size: 4	state: DIRTY
Total memory not made persistent: 7</pre>
<p>
        This indicates that three stores made to persistent memory are not
        guaranteed to be durable in case of power failure. The offending stores
        are identified by a full stack trace and the state of the store at
        program exit is shown. However, be aware that having a clean output
        does <span class="emphasis"><em>NOT</em></span> make your program fail-safe. External
        tools have to be used to verify whether your use of persistent memory
        is correct in case of unforeseen failures.
      </p>
<p>
        Pmemcheck, when run with the <a class="xref" href="pmc-manual.html#opt.mult-stores">--mult-stores</a> option,
        can also detect multiple stores made to the same persistent memory
        address before the first store has been made persistent. This can
        indicate an issue with your algorithm, where you overwrite a value
        multiple times, possibly unintentionally. The use of this option
        is connected with setting the <a class="xref" href="pmc-manual.html#opt.indiff">--indiff</a> value.
        Some implementations of for example
        <code class="computeroutput">memcpy()</code>, write the same data multiple
        times to the same location. The <a class="xref" href="pmc-manual.html#opt.indiff">--indiff</a> option
        tells pmemcheck between how many Valgrind SuperBlocks, multiple stores
        with the same value, size and address are to be ignored. An example
        output:</p>
<pre class="programlisting">
Number of stores not made persistent: 1
Stores not made persistent properly:
[0]    at 0x400A89: main (multiple_stores.c:33)
	Address: 0x4fec000	size: 8	state: DIRTY
Total memory not made persistent: 8

Number of overwritten stores: 3
Overwritten stores before they were made persistent:
[0]    at 0x400A6F: main (multiple_stores.c:30)
	Address: 0x4fec000	size: 1	state: DIRTY
[1]    at 0x400A76: main (multiple_stores.c:31)
	Address: 0x4fec000	size: 2	state: DIRTY
[2]    at 0x400A7F: main (multiple_stores.c:32)
	Address: 0x4fec000	size: 4	state: DIRTY</pre>
<p>
        If the values or sizes are different, or the stores overlap somehow,
        the event will be recorded regardless of the
        <a class="xref" href="pmc-manual.html#opt.indiff">--indiff</a> value.
      </p>
<p>
        The third type of errors reported by pmemcheck are related to probably
        inefficient use of flushes. This is strictly a performance issue and
        does not have impact on data durability. As such it is disabled by
        default, use the <a class="xref" href="pmc-manual.html#opt.flush-check">--flush-check</a> option to turn it on.
        It reports all occurrences of flushes made on non-dirty cache lines. The
        output from the flush checking analysis can look like this:
        </p>
<pre class="programlisting">
Number of redundantly flushed stores: 3
Stores flushed multiple times:
[0]    at 0x400A5B: main (flush_check.c:27)
	Address: 0x4fec000	size: 8	state: FLUSHED
[1]    at 0x400A5C: main (flush_check.c:28)
	Address: 0x4fec000	size: 8	state: FLUSHED
[2]    at 0x400A5D: main (flush_check.c:29)
	Address: 0x4fec000	size: 8	state: FLUSHED</pre>
<p>
        It indicates that the same store has been flushed multiple times,
        which is a potential performance issue.
      </p>
<p>
	In case when no stores were made to the flushed region, the program will
	yield the following output:
	</p>
<pre class="programlisting">
Number of unnecessary flushes: 3
[0]    at 0x400AB2: main (missed_flush.c:27)
	Address: 0x4fec000	size: 64
[1]    at 0x400B18: main (missed_flush.c:29)
	Address: 0x4fec040	size: 128
[2]    at 0x400B71: main (missed_flush.c:31)
	Address: 0x0	size: 64</pre>
<p>
      </p>
<p>
	Pmemcheck also allows tracking of persistent memory transactions.
	To learn more about the built-in transaction support in pmemcheck
	see <a class="xref" href="pmc-manual.html#pmc-manual.transactions" title="12.1.4. Pmemcheck transaction support">Transactions</a>. The primary type of issue
	found by pmemcheck are stores made to regions of memory not tracked
	by transactions.  An example output of the out-of-transaction stores
	has the following form:
	</p>
<pre class="programlisting">
Number of stores made outside of transactions: 2
Stores made outside of transactions:
[0]    at 0x400C3E: main (trans_impl_nest.c:39)
	Address: 0x4fec000	size: 1
[1]    at 0x400C58: main (trans_impl_nest.c:42)
	Address: 0x4fec018	size: 8</pre>
<p>
      </p>
<p>
	A different type of error message related to the transactions
	functionality within pmemcheck, are active transactions on program exit.
	This kind of error shows that some transactions have not finished
	properly. This can lead to data corruption and possibly performance
	degradation.  If any transactions are active on exit, a report with the
	following form is issued:
	</p>
<pre class="programlisting">
Number of active transactions: 1
[0]    at 0x400AE5: main (trans_impl_nest.c:32)
	tx_id: 1	 nesting: 1</pre>
<p>
      </p>
<p>
	Another type of consistency error might occur when different
	transactions are tracking the same memory region. Let's say for example
	the implementation of your application uses an undo log and two separate
	transactions add the same memory region to their undo lists. If one of
	them fails, the changes get rolled back and the resulting state of the
	whole persistent memory "pool" might be inconsistent. The warning
	message for this issue has the following form:
	</p>
<pre class="programlisting">
Number of overlapping regions registered in different transactions: 1
Overlapping regions:
[0]    at 0x400C9C: make_tx (trans_mt.c:35)
   by 0x4C2F181: start_thread (pthread_create.c:312)
   by 0x4F3F47C: clone (clone.S:111)
	Address: 0x520a010	size: 4	tx_id: 3
   First registered here:
[0]'   at 0x400C9C: make_tx (trans_mt.c:35)
   by 0x4C2F181: start_thread (pthread_create.c:312)
   by 0x4F3F47C: clone (clone.S:111)
	Address: 0x520a010	size: 4	tx_id: 2</pre>
<p>
      </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="pmc-manual.transactions"></a>12.1.4. Pmemcheck transaction support</h3></div></div></div>
<p>
	Contemporary hardware architectures guarantee that only stores up to
	a certain size can be made atomically. Here atomicity refers to non-torn
	writes and not concurrency safety. At the time of writing this
	documentation the x86-64 architecture supports 8 byte atomic writes.
	This in most cases is insufficient in real world applications.
	Therefore the need to introduce transactions, which allow larger ranges
	of persistent memory to be changed atomically. Whether transactions
	are rolled-back, redone or employ some other technique is of no
	importance to pmemcheck. What is important is that pmemcheck knows
	which regions of persistent memory are tracked by the transaction and
	can be modified freely while the transaction is active.
      </p>
<p>
	Transaction support cannot be turned off, however the runtime overhead
	is negligible if no transactions are made in the analyzed application.
	To inform pmemcheck of a new transaction start, use one of two available
	macros <a class="xref" href="pmc-manual.html#crm.start_tx">VALGRIND_PMC_START_TX</a> or
	<a class="xref" href="pmc-manual.html#crm.start_tx_n">VALGRIND_PMC_START_TX_N</a>. Depending on whether your application
	uses flattened, implicit per-thread transactions or explicit
	thread-independent transactions, use the appropriate macro to ensure
	the transactions are tracked correctly. Internally each thread has a
	list of transactions it contributes to and each transactions has a list
	of persistent memory regions which belong to the transaction. When a new
	thread starts a transaction, a new entry for the transactions is created
	with an empty persistent memory regions list. At the same time a new
	thread entry is created and the id of the transaction is added to its
	list of active transactions. If different threads are to contribute to
	the same transaction, pmemcheck has to be informed about the relation
	between threads and transactions the thread is to contribute to. To
	do this use the <a class="xref" href="pmc-manual.html#crm.add_thread_to_tx_n">VALGRIND_PMC_ADD_THREAD_TO_TX_N</a> and
	<a class="xref" href="pmc-manual.html#crm.remove_thread_from_tx_n">VALGRIND_PMC_REMOVE_THREAD_FROM_TX_N</a> macros.
      </p>
<p>
	Once the transaction is started, pmemcheck has to be informed of the
	regions which will be tracked by the transaction. To do that call
	either the <a class="xref" href="pmc-manual.html#crm.add_to_tx">VALGRIND_PMC_ADD_TO_TX</a> or the
	<a class="xref" href="pmc-manual.html#crm.add_to_tx_n">VALGRIND_PMC_ADD_TO_TX_N</a> macro. The two flavors are analogous
	to the <a class="xref" href="pmc-manual.html#crm.start_tx">VALGRIND_PMC_START_TX</a> and
	<a class="xref" href="pmc-manual.html#crm.start_tx_n">VALGRIND_PMC_START_TX_N</a> macros. The first one is for implicit
	transactions and the second for explicit transactions. Both of these
	macros will add the given region to the list of tracked persistent
	memory regions within the given transaction (implicit or explicit).
	Please note that changes made to volatile memory will
	<span class="emphasis"><em>NOT</em></span> be reported for obvious reasons.
	If there is a need to remove any of the regions	from the transaction,
	the <a class="xref" href="pmc-manual.html#crm.remove_from_tx">VALGRIND_PMC_REMOVE_FROM_TX</a> or the
	<a class="xref" href="pmc-manual.html#crm.remove_from_tx_n">VALGRIND_PMC_REMOVE_FROM_TX_N</a> macros can be used. To add
	regions of memory which are not to be checked throughout the whole
	duration of the application run, use the
	<a class="xref" href="pmc-manual.html#crm.add_global_tx_ignore">VALGRIND_PMC_ADD_TO_GLOBAL_TX_IGNORE</a> macro.
      </p>
<p>
	To end a transaction call either the <a class="xref" href="pmc-manual.html#crm.end_tx">VALGRIND_PMC_END_TX</a> or
	<a class="xref" href="pmc-manual.html#crm.end_tx_n">VALGRIND_PMC_END_TX_N</a>. As before the
	<code class="computeroutput">_N</code> suffixed versions are for
	applications using explicit transactions. Once a transaction is ended
	the transaction entry is removed along with the registered regions.
	At the same time all active thread entries have the corresponding
	transaction removed from their index. Once a thread has no more active
	transactions, it is also removed from the list of active threads. If
	you nest a transaction with the same id (which is always the case with
	implicit transactions), you bump up the nesting counter. A transaction
	will not be removed until the nesting counter hits 0. The
	counter is decremented on each transaction end.
      </p>
<p>
	Once a transaction is started, pmemcheck tracks all stores made by any
	given thread and checks whether they are made to a persistent memory
	region that is part of a transaction. If it is not, the store is
	registered and will be reported on program exit. Changes made outside
	of transactions are a possible data consistency concern, should the
	transaction be interrupted in any way. Each such event should be
	carefully analyzed. Additionally when the tool is run with
	<a class="xref" href="pmc-manual.html#opt.tx_only">--tx_only</a>, all changes to persistent memory must be
	made within a transaction (excluding the regions added by the
	<a class="xref" href="pmc-manual.html#crm.add_global_tx_ignore">VALGRIND_PMC_ADD_TO_GLOBAL_TX_IGNORE</a> macro).
      </p>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="pmc-manual.options"></a>12.2. Pmemcheck Command-line Options</h2></div></div></div>
<p>Pmemcheck-specific command-line options are:</p>
<div class="variablelist">
<a name="pmc.opts.list"></a><dl class="variablelist">
<dt>
<a name="opt.indiff"></a><span class="term">
	     <code class="option">--indiff=&lt;uint&gt; [default: 0 SBlocks] </code>
	    </span>
</dt>
<dd><p>
            This option is only used in conjunction with
            <a class="xref" href="pmc-manual.html#opt.mult-stores">--mult-stores</a>. Between this many Valgrind
            SuperBlocks, stores of the same size, address and value will not
            be counted as an error.
          </p></dd>
<dt>
<a name="opt.mult-stores"></a><span class="term">
		  <code class="option">--mult-stores=&lt;yes|no&gt; [default: no] </code>
		</span>
</dt>
<dd><p>
            This option enables analyzing multiple stores to the same region
            of memory between persistent memory barriers. This might indicate
            erroneous usage of persistent memory by your application. If you run
            into problems which are independent of your application (I have
            seen <code class="computeroutput">memcpy()</code> do this on numerous
            occasions), fine tune the <a class="xref" href="pmc-manual.html#opt.indiff">--indiff</a> value to get
            rid of false-positives.
          </p></dd>
<dt>
<a name="opt.log-stores"></a><span class="term">
		  <code class="option">--log-stores=&lt;yes|no&gt; [default: no] </code>
		</span>
</dt>
<dd><p>
            Turns on logging all persistent memory related events (most
            <a class="xref" href="pmc-manual.html#pmc-manual.client_requests" title="12.3. Pmemcheck Client Requests">Pmemcheck Client Requests</a> and stores to
            persistent memory) in a human-readable, parsable format. This is
            useful if some postprocessing or in depth analysis is to be made.
            Depending on the usage, the log output can be huge - use with
            caution.
          </p></dd>
<dt>
<a name="opt.print-summary"></a><span class="term">
		  <code class="option">--print-summary=&lt;yes|no&gt; [default: yes] </code>
		</span>
</dt>
<dd><p>
            This option enables or inhibits printing the analysis summary.
            This option is particularly useful together with
            <a class="xref" href="pmc-manual.html#opt.log-stores">--log-stores</a>.
          </p></dd>
<dt>
<a name="opt.flush-check"></a><span class="term">
          <code class="option">--flush-check=&lt;yes|no&gt; [default: no] </code>
        </span>
</dt>
<dd><p>
            When this option is turned on, pmemcheck checks if your
            application flushes non-dirty cachelines. Be aware that the tool
            does not recognize flushes, it depends on your application
            informing it about the explicit flushes being made. To do that
            use the <a class="xref" href="pmc-manual.html#crm.flush">VALGRIND_PMC_DO_FLUSH</a> macro.
          </p></dd>
<dt>
<a name="opt.flush-align"></a><span class="term">
          <code class="option">--flush-align=&lt;yes|no&gt; [default: no] </code>
        </span>
</dt>
<dd><p>
            This flag turns on flush aligning to the native machine's cache
            line size. It might sometimes prove beneficial to analyze the
            application with full cache line flushing. Setting this in
            conjunction with <a class="xref" href="pmc-manual.html#opt.flush-check">--flush-check</a> might result in
            false-positives.
          </p></dd>
<dt>
<a name="opt.tx_only"></a><span class="term">
          <code class="option">--tx_only=&lt;yes|no&gt; [default: no] </code>
        </span>
</dt>
<dd><p>
            This flag turns on strict transaction checks in pmemcheck.
	    When turned on, pmemcheck will track all changes made to memory,
	    which were not registered as being part of a transaction. This is
	    a potential data consistency issue, as these changes will not be
	    rolled-back/redone on transaction recovery, after an interruption.
	    All changes, also those made without a running transaction, will
	    be reported by the tool. For more information on transaction support
	    built into pmemcheck see <a class="xref" href="pmc-manual.html#pmc-manual.transactions" title="12.1.4. Pmemcheck transaction support">Transactions</a>.
          </p></dd>
</dl>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="pmc-manual.client_requests"></a>12.3. Pmemcheck Client Requests</h2></div></div></div>
<p>Pmemcheck-specific client requests are:</p>
<div class="variablelist">
<a name="pmc.crm.list"></a><dl class="variablelist">
<dt>
<a name="crm.reg_pmem"></a><span class="term">
		  <code class="option">
            VALGRIND_PMC_REGISTER_PMEM_MAPPING(addr, size) 
          </code>
		</span>
</dt>
<dd><p>
            Registers in pmemcheck a persistent memory region. This is the basic
            macro used for persistent memory analysis. Only stores to one of the
            registered regions are taken into account in pmemcheck.
          </p></dd>
<dt>
<a name="crm.reg_file"></a><span class="term">
		  <code class="option">
            VALGRIND_PMC_REGISTER_PMEM_FILE(desc, addr_base, size, offset)
          </code>
		</span>
</dt>
<dd><p>
            Register a persistent memory file. This macro does not register
            a persistent memory region, it is used to link the regions to
            a specific file. This is especially useful for any kind of post
            processing. Returns <code class="computeroutput">1</code>
	    when the given file could not be found
	    <code class="computeroutput">0</code> otherwise.
          </p></dd>
<dt>
<a name="crm.rem_pmem"></a><span class="term">
		  <code class="option">
            VALGRIND_PMC_REMOVE_PMEM_MAPPING(addr, size) 
          </code>
		</span>
</dt>
<dd><p>
            Remove a region from the pmemcheck persistent memory register.
            If the removed region overlaps a registered region, it will
            be spliced. Very useful for carving out parts of persistent memory
            which are used as volatile memory.
          </p></dd>
<dt>
<a name="crm.is_pmem"></a><span class="term">
		  <code class="option">
            VALGRIND_PMC_CHECK_IS_PMEM_MAPPING(addr, size) 
          </code>
		</span>
</dt>
<dd><p>
            Checks if a given regions is registered as a persistent memory
            mapping in pmemcheck. Returns <code class="computeroutput">0</code>
            if not, <code class="computeroutput">1</code> if fully within mapping,
            <code class="computeroutput">2</code> otherwise.
          </p></dd>
<dt>
<a name="crm.print_map"></a><span class="term">
		  <code class="option">VALGRIND_PMC_PRINT_PMEM_MAPPINGS</code>
		</span>
</dt>
<dd><p>
            Prints out the registered persistent memory mappings.
          </p></dd>
<dt>
<a name="crm.flush"></a><span class="term">
		  <code class="option">VALGRIND_PMC_DO_CLFLUSH(addr, size)</code>
        </span>
</dt>
<dd><p>
            Simulates a flush on all stores to persistent memory within the
            given address range. Depending on the
            <a class="xref" href="pmc-manual.html#opt.flush-align">--flush-align</a> option the flush address might
            be aligned to the native machine's cache line size.
          </p></dd>
<dt>
<a name="crm.fence"></a><span class="term">
		  <code class="option">VALGRIND_PMC_DO_FENCE</code>
		</span>
</dt>
<dd><p>
            Simulates a memory fence for the appropriate stores to registered
            persistent memory regions.
          </p></dd>
<dt>
<a name="crm.clean"></a><span class="term">
	  <code class="option">VALGRIND_PMC_SET_CLEAN</code>
	</span>
</dt>
<dd><p>
	    Sets the desired region of persistent memory as clean. This may
	    be useful for discarding changes made to persistent memory.
          </p></dd>
<dt>
<a name="crm.wr_stats"></a><span class="term">
	  <code class="option">VALGRIND_PMC_WRITE_STATS</code>
	</span>
</dt>
<dd><p>
            Writes persistent memory analysis statistics.
          </p></dd>
<dt>
<a name="crm.start_tx"></a><span class="term">
          <code class="option">VALGRIND_PMC_START_TX</code>
        </span>
</dt>
<dd><p>
            Starts a transaction with an implicit transaction id. The id will be
            the id of the thread which issues the client request. Nesting
            transactions is allowed - the nesting counter of the transaction
            is incremented by <code class="computeroutput">1</code>.
          </p></dd>
<dt>
<a name="crm.start_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_START_TX_N(txn)</code>
        </span>
</dt>
<dd><p>
            Starts a transaction with the given transaction id.  Nesting
            transactions is allowed - the nesting counter of the transaction
            is incremented by <code class="computeroutput">1</code>.
          </p></dd>
<dt>
<a name="crm.end_tx"></a><span class="term">
          <code class="option">VALGRIND_PMC_END_TX</code>
        </span>
</dt>
<dd><p>
            Ends a transaction with an implicit transaction id. The id will be
            the id of the thread which issues the client request. The nesting
            counter of the transaction is decremented by
            <code class="computeroutput">1</code>. If it hits
            <code class="computeroutput">0</code>, the transaction is no longer
            tracked by pmemcheck. Returns <code class="computeroutput">1</code>
            when no matching and <code class="computeroutput">0</code> otherwise.
          </p></dd>
<dt>
<a name="crm.end_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_END_TX_N(txn)</code>
        </span>
</dt>
<dd><p>
            Ends a transaction with the given transaction id. The nesting
            counter of the transaction is decremented by
            <code class="computeroutput">1</code>. If it hits
            <code class="computeroutput">0</code>, the transaction is no longer
            tracked by pmemcheck. Returns <code class="computeroutput">1</code>
            when no matching and <code class="computeroutput">0</code> otherwise.
          </p></dd>
<dt>
<a name="crm.add_to_tx"></a><span class="term">
          <code class="option">VALGRIND_PMC_ADD_TO_TX(addr, size)</code>
        </span>
</dt>
<dd><p>
            Adds a persistent memory region to the implicit transaction. Stores
            made during the transaction to persistent memory outside of the
            registered regions will be reported as a potential data consistency
            issue. Returns <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">2</code> when
            the current thread does not participate in this transaction and
            <code class="computeroutput">0</code> otherwise. Multiple additions
	    of the same region do not result in multiple region entries. They
	    are registered as contiguous space and not separate enteties.
          </p></dd>
<dt>
<a name="crm.add_to_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_ADD_TO_TX_N(txn, addr, size)</code>
        </span>
</dt>
<dd><p>
            Adds a persistent memory region to the given transaction. Stores
            made during the transaction to persistent memory outside of the
            registered regions will be reported as a potential data consistency
            issue. Returns <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">2</code> when
            the current thread does not participate in this transaction and
            <code class="computeroutput">0</code> otherwise. Multiple additions
	    of the same region do not result in multiple region entries. They
	    are registered as contiguous space and not separate enteties.
          </p></dd>
<dt>
<a name="crm.remove_from_tx"></a><span class="term">
          <code class="option">VALGRIND_PMC_REMOVE_FROM_TX(addr, size)</code>
        </span>
</dt>
<dd><p>
            Removes a persistent memory region from the implicit transaction.
            Returns <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">2</code> when
            the current thread does not participate in this transaction and
            <code class="computeroutput">0</code> otherwise. Removing a region once
	    removes it from the transaction, regardless how many times it was
	    added.
          </p></dd>
<dt>
<a name="crm.remove_from_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_REMOVE_FROM_TX_N(txn, addr, size)</code>
        </span>
</dt>
<dd><p>
            Removes a persistent memory region from the given transaction.
            Returns <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">2</code> when
            the current thread does not participate in this transaction and
            <code class="computeroutput">0</code> otherwise. Removing a region once
	    removes it from the transaction, regardless how many times it was
	    added.
          </p></dd>
<dt>
<a name="crm.add_thread_to_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_ADD_THREAD_TO_TX_N(txn)</code>
        </span>
</dt>
<dd><p>
            Adds the current thread to the given transaction. Returns
            <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">0</code> otherwise.
          </p></dd>
<dt>
<a name="crm.remove_thread_from_tx_n"></a><span class="term">
          <code class="option">VALGRIND_PMC_REMOVE_THREAD_FROM_TX_N(txn,)</code>
        </span>
</dt>
<dd><p>
            Removes the current thread from the given transaction.
            Returns <code class="computeroutput">1</code> when no matching
            transaction was found, <code class="computeroutput">2</code> when
            the current thread does not participate in this transaction and
            <code class="computeroutput">0</code> otherwise.
          </p></dd>
<dt>
<a name="crm.add_global_tx_ignore"></a><span class="term">
          <code class="option">VALGRIND_PMC_ADD_TO_GLOBAL_TX_IGNORE(addr, size)</code>
        </span>
</dt>
<dd><p>
            Adds a persistent memory region to the global ignore list. Once
            added the memory region cannot be removed until the end of the
            execution of the application. Out of transaction writes to these
            regions will not be reported.
          </p></dd>
</dl>
</div>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="pmc-manual.monitor_commands"></a>12.4. Pmemcheck Monitor Commands</h2></div></div></div>
<p>
        The Pmemcheck tool provides monitor commands handled by the Valgrind
        gdbserver (see
        <a class="xref" href="manual-core-adv.html#manual-core-adv.gdbserver-commandhandling" title="3.2.5. Monitor command handling by the Valgrind gdbserver">Monitor command handling by the Valgrind gdbserver</a>). Tool
        specific monitor commands are:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
            <code class="varname">help</code> prints monitor help message.
          </p></li>
<li class="listitem"><p>
            <code class="varname">print_stats</code> prints registered pmemcheck statistics.
          </p></li>
<li class="listitem"><p>
            <code class="varname">print_pmem_regions</code> prints registered persistent
            memory regions.
          </p></li>
<li class="listitem"><p>
            <code class="varname">print_log_regions</code> prints registered loggable
            persistent memory regions.
          </p></li>
</ul></div>
</div>
</div>
<div>
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
<tr>
<td rowspan="2" width="40%" align="left">
<a accesskey="p" href="lk-manual.html">&lt;&lt; 11. Lackey: an example tool</a> </td>
<td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td>
<td rowspan="2" width="40%" align="right"> <a accesskey="n" href="nl-manual.html">13. Nulgrind: the minimal Valgrind tool &gt;&gt;</a>
</td>
</tr>
<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
</table>
</div>
</body>
</html>
